---
title: Controllers-Hooks Ecosystem
---

## Introduction

The Controllers-Hooks ecosystem includes a set of blueprints which allow to easily create controller-based automations in just a few clicks. As the name implies, it consists of two main blueprint categories: Controllers and Hooks.

## Controllers

**Controllers** are blueprints which allow to easily integrate a wide range of controllers (wall switches, remotes, dimmers, etc.) and use them to run a set of actions when interacting with them. They consist in a practical abstraction layer for building controlled-based automations without worrying about the handling of RAW controller events and the integration used to connect controllers to Home Assistant (Zigbee2MQTT, ZHA, deCONZ, ZWave, Shelly, proprietary hubs, etc.).

:::info
The type of exposed events depends on the controller model. Some controllers can also expose virtual events. You can read more about them [here](#virtual-events).
:::

Most importantly, beside providing custom action sequences to Controller blueprints, you can connect Controllers with [Hooks](#hooks).

### Helper - Last Controller Event Input

The `helper_last_controller_event` (Helper - Last Controller Event) input is a generic `input_text` entity which serves as a permanent storage area for a Controller automation. Currently the following information is stored:

- **Last Controller event**: the latest event which was fired by the controller.
- **Last triggered time**: the date/time the latest controller event was fired.

The stored info is used in many different ways to implement the blueprint's core functionality:

- **Action Recognition**: Some controllers use the info contained in the helper to recognize some actions. This varies between different controller models and integrations. Since natively the device doesn't allow to distinguish between certain events, the blueprint needs to store the last event, and take advantage of this information to identify subsequent actions.
- **Virtual Events**: The last controller event is used to implement virtual events. You can read more about them [here](#virtual-events).

This field requires that you have an existing text helper. Therefore, before setting up the automation, manually create a brand new `input_text` entity in your Home Assistant instance (e.g. from [the Helpers configuration page](https://my.home-assistant.io/redirect/helpers/)), then provide it to the blueprint while configuring the automation.

:::caution
Make sure the text input is not altered by any other agents. The provided entity is used as a permanent storage area for the controller automation; any change to its state not carried out by the respective automation could lead to inconsistencies and unexpected behaviour.

Therefore, you should create **a separate text input for each Controller blueprint** you're configuring.
:::

### Virtual Events

Virtual events are particular events which are not natively exposed by the controller itself. They're instead generated by the blueprint, which derives them from the incoming RAW controller events and by using the `helper_last_controller_event` input and additional helpers.

Controllers, depending on the device model and functionality, currently support the following virtual events:

- **Virtual button double press**:

  Implemented by relying on the `helper_last_controller_event` input, used to store the last short press event, and a delay (specified with the `helper_double_press_delay` input), which represents the maximum time gap between the first and second short press required to trigger the virtual double press.

  When double press events are enabled for a specific button, clicking the button results in the automation first waiting for the second button press, then, if none is received within the provided delay, executing the short press action.

  If double press events are disabled for a specific button, the corresponding single press action will be executed immediately when the button is pressed.

:::tip
Such events can introduce some delay in the automation, therefore they can be disabled when not needed, thanks to a dedicated blueprint input.
:::

## Hooks

**Hooks** are blueprints which seamlessly integrate with [Controllers](#controllers) to enable control of lights, media players, covers and much more, without you ever writing a single line of code.

While Controllers are responsible for integrating the hardware and exposing an abstract interface to the user, Hooks can, as the name suggests, link to this interface and listen for events fired by a Controller. With the received events, Hooks take care of providing the actual control functionality for common use cases (eg. controlling a Media Player).

## How to build a controller-based automation

### Basic Usage: Controller with custom actions

![Basic Usage: Controller with custom actions](/img/awesome-ha-blueprints-04.svg)

The simplest use case for such blueprints consists in creating an entirely custom controller-based automation, which can be done by using only a Controller blueprint.

When setting up an automation with a Controller blueprint, you may be asked to select the integration used to connect the controller to Home Assistant, and the `device` (depending on the integration) representing the Controller. You can then specify a sequence of actions for each of the events the controller exposes.

Each time an event is fired by the controller (eg. button press) the automation will run the provided custom action corresponding to that specific event.

:::tip
Even in this simple scenario, you can still benefit from most of the features of the ecosystem: the blueprint will take care of handling the RAW events fired by the controller, as well as providing virtual events (eg. double clicks) not natively exposed by the controller.
:::

### Controller and Hook

![Controller and Hook](/img/awesome-ha-blueprints-01.svg)

If you want to build a controller-based automation with Hooks, first create an automation with a Controller blueprint. You can then build an automation with the desired Hook blueprint, **making sure that you provide the same controller `device` used in the corresponding Controller blueprint**. This key step will link the two automations and ensure the Hook will respond to events fired by the Controller.

:::info
Please note that not all controllers might be used with each of the available Hooks. Check out the Hook documentation for the list of supported controllers for that specific Hook.
:::

### Controller and Hook + Custom actions

![Controller and Hook + Custom actions](/img/awesome-ha-blueprints-03.svg)

If you need to customize certain actions or extend a Hook functionality, you can also provide custom actions to the Controller blueprint, which will be run when a certain event is raised.

### Controller with multiple Hooks

![Controller with multiple Hooks](/img/awesome-ha-blueprints-05.svg)

For more flexibility, you can link multiple Hooks to the same Controller: just create a Controller automation, then build as many Hook automations as needed.

This might be useful when you'd like to control multiple devices with the same controller (eg. multiple media players or lights) without relying on Home Assistant groups.

## Examples

### Control a media player with an IKEA E1743

```yaml
# Controller automation: integrate the IKEA E1743
- alias: Controller - IKEA E1743 Kitchen
  description: ''
  use_blueprint:
    path: EPMatt/ikea_e1743.yaml
    input:
      integration: Zigbee2MQTT
      controller_device: IKEA E1743 Kitchen
      helper_last_controller_event: input_text.ikea_e1743_helper
      button_up_double_press: true
      button_down_double_press: true

# Hook automation: Link the media player with the Controller
- alias: Hook - Control Kitchen Media Player with E1743
  description: ''
  use_blueprint:
    path: EPMatt/media_player.yaml
    input:
      # Provide the same value used in the Controller automation
      # This ensures this automation will catch events fired by the E1743
      controller_device: IKEA E1743 Kitchen
      controller_model: IKEA E1743 On/Off Switch
      media_player: media_player.kitchen
```

### Light control with an IKEA E1810 + activate scene with double click

```yaml
# Controller automation: integrate the IKEA E1810
- alias: Controller - IKEA E1810 Living Room
  description: ''
  use_blueprint:
    path: EPMatt/ikea_e1524_e1810.yaml
    input:
      integration: Zigbee2MQTT
      controller_device: IKEA E1810 Living Room
      # Example of custom action
      # activate a scene when double clicking the center button
      action_button_center_double:
        - scene: scene.cinema_mode

# Hook automation: link the light with the Controller
- alias: Hook - Control living room lights with IKEA E1810
  description: ''
  use_blueprint:
    path: EPMatt/light.yaml
    input:
      light_color_mode: RGB
      # Provide the same value used in the Controller automation
      # This ensures this automation will catch events fired by the E1810
      controller_device: IKEA E1810 Living Room
      controller_model: IKEA E1524/E1810 5-Button remote
      light: light.livingroom_ceiling
```

## How does it work

:::note
This section discusses the communication and inner implementation of Controllers and Hooks. You don't need to read or know it to properly use these blueprints.
:::

:::caution Note
This documentation section is currently under review.
:::

![Under the hood](/img/awesome-ha-blueprints-02.svg)
